---
section: 99-Packages
name: babel-plugin
order: 4
---

# @compiled/babel-plugin

import { Lozenge, HorizontalStack } from '@compiled/website-ui';

<HorizontalStack gap={0.5} spacing={2}>
  <Lozenge>Babel 7</Lozenge>
</HorizontalStack>

[Babel plugin](https://babeljs.io) used to bake styles into your JavaScript.
See [installation](/installation#babel) for setup instructions.

```bash
npm install @compiled/babel-plugin --save-dev
```

> **Double transform** <br/> When configuring Babel watch out for inadvertently transforming your code with Compiled twice if _also using one of the bundler packages_.
> Utilizing [JavaScript configuration files](https://babeljs.io/docs/en/configuration#javascript-configuration-files) can help you conditionally set plugins based on your running environment.

## Options

Configure in your Babel config.

```json
// .babelrc
{
  "plugins": [
    [
      "@compiled/babel-plugin",
      {
        "importReact": true,
        "cache": true
      }
    ]
  ]
}
```

If you choose to configure Compiled through Webpack or Parcel (recommended), you can pass options for `@compiled/babel-plugin` through those configurations. See [`@compiled/webpack-loader`](/pkg-webpack-loader) and [`@compiled/parcel-config`](/pkg-parcel-config) for more information.

`@compiled/babel-plugin` supports the following options:

- `addComponentName`
- `cache`
- `classHashPrefix`
- `classNameCompressionMap`
- `extensions`
- `flattenMultipleSelectors`
- `importReact`
- `importSources`
- `increaseSpecificity`
- `nonce`
- `onIncludedFiles`
- `optimizeCss`
- `parserBabelPlugins`
- `processXcss`
- `resolver`
- `sortAtRules`

#### addComponentName

Add the component name as a class name to the DOM in non-production environments, if `styled` is used.

- Type: `boolean`
- Default: `false`

#### cache

Will cache the result of statically evaluated imports.

- `true` will cache for the duration of the node process
- `'single-pass'` will cache for a single pass of a file
- `false` turns caching off

* Type: `boolean | 'single-pass'`
* Default: `true`

#### classHashPrefix

Adds a prefix to the generated hashed css rule names. The valued passed to it gets hashed in conjunction with the rest of the rule declaration.

This is useful when `@compiled` is being used in a micro frontend environment by multiple packages and you want to avoid specificity issues. Please note that mixing this with extraction is not supported and Parcel or Webpack will throw an error if combined.

The currently accepted regex for this value is `^[a-zA-Z\-_]+[a-zA-Z\-_0-9]*$`.

- Type: `string`
- Default: `undefined`

#### classNameCompressionMap

Don't use this!

An internal and experimental option used to compress class names.

Note that in `@compiled/webpack-loader` and `@compiled/parcel-config`, `classNameCompressionMap` requires `extract` to be true as well.

#### extensions

Extensions that we should consider code. We use these to identify if a file should be parsed.

- Type: `string[]`
- Default: `['.js', '.jsx', '.ts', '.tsx']`

#### flattenMultipleSelectors

Flatten multiple selectors into separate rules to better deduplicate and sort styles, eg.:

```tsx
css({
  '&:hover, &:focus': {
    color: 'red',
  },
});
```

Is transformed into the same code as this would be:

```tsx
css({
  '&:hover': { color: 'red' },
  '&:focus': { color: 'red' },
});
```

- Type: `boolean`
- Default: `true`

#### importReact

Will import React into the module if it is not found.
When using `@babel/preset-react` with the [automatic runtime](https://babeljs.io/docs/en/babel-preset-react#react-automatic-runtime) this is not needed and can be set to `false`.

- Type: `boolean`
- Default: `true`

#### importSources

Additional libraries that should be parsed as though they were `@compiled/react` imports. `@atlaskit/css` is a first-class alias that is supported internally and is not necessary to include here.

Specifying this is important if you are using Compiled APIs through another package using the `createStrictAPI` function.

- Type: `string[]`
- Default: `undefined`

#### increaseSpecificity

An experimental option that increases the specificity of all generated Compiled classes. Don't use this!

#### nonce

[Security nonce](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) that will be applied to inline style elements if defined.

- Type: `string`
- Default: `false`

#### onIncludedFiles

An internal option. Callback fired at the end of the file pass when files have been included in the transformation.

- Type: `(files: string[]) => void`
- Default: `undefined`

#### optimizeCss

Will run additional `cssnano` plugins to normalize CSS during the build.

- Type: `boolean`
- Default: `true`

#### parserBabelPlugins

Babel parser plugins to be used when parsing the source code. Define these to enable extra babel parsers (for example, typescript).
See the [babel docs](https://babeljs.io/docs/en/plugins/#syntax-plugins) for more context.

Usually, you will set this option through [`@compiled/parcel-config`] or [`@compiled/webpack-loader`](/webpack-loader) -- see there for examples.

#### processXcss

An option we are only using internally. Don't use!

#### resolver

A custom resolver used to statically evaluate import declarations, specified as either an object or module path. If this is an object, it should contain a `resolveSync` function with the following type signature: `(context: string, request: string) => string`.

- Type: `string | Resolver`
- Default: `undefined`

#### sortAtRules

Unused.
